home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / other / pmdev / popupmenu.doc < prev    next >
Text File  |  2000-02-28  |  30KB  |  882 lines
  1. TABLE OF CONTENTS
  2.  
  3. popupmenu.library/--background--
  4. popupmenu.library/--hooks--
  5. popupmenu.library/PM_AbortHook
  6. popupmenu.library/PM_AlterState
  7. popupmenu.library/PM_ExLstA
  8. popupmenu.library/PM_FilterIMsgA
  9. popupmenu.library/PM_FindItem
  10. popupmenu.library/PM_FreePopupMenu
  11. popupmenu.library/PM_GetItemAttrsA
  12. popupmenu.library/PM_GetVersion
  13. popupmenu.library/PM_InsertMenuItemA
  14. popupmenu.library/PM_ItemChecked
  15. popupmenu.library/PM_LayoutMenuA
  16. popupmenu.library/PM_MakeIDListA
  17. popupmenu.library/PM_MakeItemA
  18. popupmenu.library/PM_MakeMenuA
  19. popupmenu.library/PM_OpenPopupMenuA
  20. popupmenu.library/PM_ReloadPrefs
  21. popupmenu.library/PM_RemoveMenuItem
  22. popupmenu.library/PM_SetItemAttrsA
  23. popupmenu.library/--background--             popupmenu.library/--background--
  24.  
  25.    PURPOSE
  26.         The popupmenu.library provides developers with an easy way of adding
  27.         user configurable popup and pulldown menus to their applications.
  28.         
  29.    COPYRIGHT
  30.         The popupmenu.library is ©2000 by Henrik Isaksson.
  31.         
  32. popupmenu.library/--hooks--                       popupmenu.library/--hooks--
  33.  
  34.    CALLBACK HOOKS
  35.         Callback hooks are used by popupmenu.library for several purposes,
  36.         including handling of localized strings, handling of user input (ie.
  37.         menu selection) and building dynamic menus. All of theese hooks have
  38.         some things in common, and they will be described here.
  39.  
  40.         For general information about callbacks hooks, see the
  41.         utility.library documentation and utility/hooks.h.
  42.  
  43.         When a callback hook function is called by popupmenu.library, the
  44.         register contents are as follows:
  45.  
  46.         o a pointer to the functions hook structure is in A0.
  47.                 
  48.         o a pointer to the affected object is put in A2. This is usually a
  49.           struct PopupMenu pointer. Some future functions may use other
  50.           objects.
  51.  
  52.         o a pointer to an array of arguments is passed in A1. Theese are
  53.           specific to each hook.
  54.  
  55.    EXAMPLE
  56.         
  57.         /* First we declare the function: */
  58.         /* Note that the keywords __asm, __saveds, register, etc. are */
  59.         /* specific to SAS/C. */
  60.         
  61.         ULONG __saveds __asm MyPMHookFunc(
  62.                         register __a0 struct Hook *hook,
  63.                         register __a2 struct PopupMenu *pm,
  64.                         register __a1 APTR *args)
  65.         {
  66.                 /* hook = pointer to the hook structure declared below. */
  67.  
  68.                 /* pm = pointer to the item that the hook function call */
  69.                 /*      is caused by. */
  70.  
  71.                 /* args = array of arguments. */
  72.                 
  73.                 /* Example: You want to access the first argument which is */
  74.                 /*          an ULONG. */
  75.                 
  76.                 ULONG arg1 = *((ULONG *)args[0]);
  77.         }
  78.         
  79.         /* Second: Filling out the Hook structure. */
  80.  
  81.         struct Hook MyPMHook;
  82.         
  83.         MyPMHook.h_Entry = (HOOKFUNC) MyPMHookFunc;
  84.  
  85.         /* Now you can pass the structure as a pointer to one of the */
  86.         /* popupmenu functions. */
  87.  
  88.    SEE ALSO
  89.         PM_MakeItemA(), PM_OpenPopupMenuA(), utility.library/CallHookPkt(),
  90.         <utility/hooks.h>
  91.  
  92. popupmenu.library/PM_AbortHook                 popupmenu.library/PM_AbortHook
  93.  
  94.    NAME
  95.         PM_AbortHook -- Find out if user wants to abort menu operation. (V9)
  96.  
  97.    SYNOPSIS
  98.         abort = PM_AbortHook(handle);
  99.         D0                   A0
  100.  
  101.         BOOL PM_AbortHook(APTR);
  102.  
  103.    FUNCTION
  104.         This function is used to find out if the user has moved the mouse
  105.         pointer outside of the region which opens the menu. It should be
  106.         called periodically (as often as possible).
  107.         PM_AbortHook() may redraw the menu when it is called, if the delay
  108.         since last call has passed a certain treshold (default is 80 ms).
  109.  
  110.    INPUTS
  111.         handle - pointer to private data passed to the hook function through
  112.                  a pointer in A1.
  113.  
  114.    RESULT
  115.         Returns TRUE if you should stop doing whatever you are doing, and
  116.         return.
  117.         If FALSE is returned, just keep on like nothing happened.
  118.  
  119.    EXAMPLE
  120.  
  121.         struct PopupMenu * __saveds __asm SubConstructFunc(
  122.                 register __a0 struct Hook *hook,
  123.                 register __a2 struct PopupMenu *selected,
  124.                 register __a1 APTR *handle)
  125.         {
  126.                 BOOL abort=FALSE;
  127.  
  128.                 do {
  129.  
  130.                         /* Do something to the menu */
  131.                         
  132.                         abort = PM_AbortHook(*handle); /* Abort? */
  133.  
  134.                 } while(!abort);
  135.         }
  136.  
  137.    SEE ALSO
  138.         PM_MakeItemA(), <libraries/pm.h>
  139.  
  140. popupmenu.library/PM_AlterState               popupmenu.library/PM_AlterState
  141.  
  142.    NAME
  143.         PM_AlterState -- Simulate a (de-)selection of a checked item. (V5)
  144.  
  145.    SYNOPSIS
  146.         PM_AlterState(base, ids, action);
  147.                       A1    A2   D1
  148.  
  149.         void PM_AlterState(struct PopupMenu *pm, struct PM_IDLst *ids,
  150.                         UWORD action);
  151.  
  152.    FUNCTION
  153.         This function will change the state of checkable/mx items in the
  154.         list 'ids', depending on their kind (exclude/include/reflect/inverse)
  155.         and the value of 'action'.
  156.  
  157.    INPUTS
  158.         base   - pointer to a PopupMenu structure.
  159.         ids    - linked PM_IDLst list.
  160.         action - either PMACT_DESELECT (2) or PMACT_SELECT (3).
  161.  
  162. popupmenu.library/PM_ExLstA                       popupmenu.library/PM_ExLstA
  163.  
  164.    NAME
  165.         PM_ExLstA -- Build a list of ID numbers for mutual exclusion. (V6)
  166.  
  167.    SYNOPSIS
  168.         list = PM_ExLstA(id);
  169.         D0               A1
  170.  
  171.         list = PM_ExLst(id1, ...);
  172.  
  173.         struct PM_IDLst *PM_ExLstA(ULONG *id);
  174.  
  175.         struct PM_IDLst *PM_ExLst(ULONG id1, ...);
  176.  
  177.    FUNCTION
  178.         This function is used to build lists of ID numbers, that are needed
  179.         for the PM_Exclude tag.
  180.         The array of ID's is ended by NULL.
  181.  
  182.    INPUTS
  183.         id - array of ID numbers
  184.  
  185.    RESULT
  186.         Returns a list of ID's, or NULL if it ran out of memory.
  187.         You don't really need to care about what it returns, just pass it
  188.         on to @{"PM_MakeItemA()" LINK PM_MakeItemA}.
  189.  
  190.    SEE ALSO
  191.         PM_MakeIDListA(), PM_MakeItemA(), <libraries/pm.h>
  192.  
  193. popupmenu.library/PM_FilterIMsgA             popupmenu.library/PM_FilterIMsgA
  194.  
  195.    NAME
  196.         PM_FilterIMsgA -- Handle keyboard shortcuts. (V6)
  197.  
  198.    SYNOPSIS
  199.         userdata = PM_FilterIMsgA(window, menu, imsg, tags);
  200.         D0                       A1      A2    A3    A5
  201.  
  202.         userdata = PM_FilterIMsg(window, menu, imsg, tags, ...);
  203.  
  204.         APTR PM_FilterIMsgA(struct Window *, struct PopupMenu *,
  205.                 struct IntuiMessage *, struct TagItem *);
  206.  
  207.         APTR PM_FilterIMsg(struct Window *, struct PopupMenu *,
  208.                 struct IntuiMessage *, ULONG, ...);
  209.  
  210.    FUNCTION
  211.         This function handles keyboard shortcuts.
  212.         It compares 'imsg' against IDCMP_VANILLAKEY, if one is found, that
  213.         item's UserData is returned, or the MenuHandler hook is called.
  214.         Remember to set IDCMP_VANILLAKEY for the window(s) you use for user
  215.         input.
  216.  
  217.    INPUTS
  218.         window = pointer to the parent window.
  219.         menu   = pointer to a popup menu.
  220.         imsg   = IntuiMessage to be filtered.
  221.  
  222.    TAGS
  223.         Accepts the same tags as PM_OpenPopupMenuA, in addition to those
  224.         listed below:
  225.  
  226.         PM_AutoPullDown - (BOOL) Set this to TRUE if you want a pulldown
  227.                           menu opened automatically, when the user presses
  228.                           RMB.
  229.                           You will have to use WFLG_RMBTRAP and
  230.                           IDCMP_MOUSEBUTTONS to get it working.
  231.  
  232.    RESULT
  233.         The UserData of the item that was selected, or NULL.
  234.         If MultiSelect is enabled, this result should not be used, since it
  235.         would not be reliable when the user selects several items.
  236.         (The user can ofcourse only select more than one item if the tag
  237.         PM_AutoPullDown is used)
  238.  
  239.    SEE ALSO
  240.         PM_OpenPopupMenuA()
  241.  
  242. popupmenu.library/PM_FindItem                   popupmenu.library/PM_FindItem
  243.  
  244.    NAME
  245.         PM_FindItem -- Find an item in a popupmenu list. (V3)
  246.  
  247.    SYNOPSIS
  248.         item = PM_FindItem(menu, id);
  249.         D0                 A1    D1
  250.  
  251.         struct PopupMenu *PM_FindItem(struct PopupMenu *, ULONG);
  252.  
  253.    FUNCTION
  254.         Find the pointer to an item using the ID number.
  255.  
  256.    INPUTS
  257.         menu = pointer to a popup menu list.
  258.         id   = ID number (PM_ID).
  259.  
  260.    RESULT
  261.         Returns a pointer to the found item, or NULL if unsuccessful.
  262.         
  263.    SEE ALSO
  264.  
  265. popupmenu.library/PM_FreePopupMenu         popupmenu.library/PM_FreePopupMenu
  266.  
  267.    NAME
  268.         PM_FreePopupMenu -- Free a menu list created by @{"PM_MakeMenuA()" LINK PM_MakeMenuA}.
  269.  
  270.    SYNOPSIS
  271.         PM_FreePopupMenu(popupmenu);
  272.                          a1
  273.  
  274.         void PM_FreePopupMenu(struct PopupMenu *);
  275.  
  276.    FUNCTION
  277.         This function is used to free the list of menu items created by
  278.         PM_MakeItemA(), and PM_MakeMenuA().
  279.  
  280.    INPUTS
  281.         popupmenu - pointer to a popup menu to free.
  282.  
  283.    SEE ALSO
  284.         PM_MakeItemA(), PM_MakeMenuA()
  285.  
  286. popupmenu.library/PM_GetItemAttrsA         popupmenu.library/PM_GetItemAttrsA
  287.  
  288.    NAME
  289.         PM_GetItemAttrsA -- Get attribute values for an object. (V3)
  290.  
  291.    SYNOPSIS
  292.         result = PM_GetItemAttrsA(item, tags);
  293.         D0                        A2    A1
  294.  
  295.         ULONG PM_GetItemAttrsA(struct PopupMenu *, struct TagItem *);
  296.  
  297.         result = PM_GetItemAttrs(item, tag1, ...);
  298.  
  299.         ULONG PM_GetItemAttrs(struct PopupMenu *, ULONG, ...);
  300.  
  301.    FUNCTION
  302.         Used to get attributes from an item.
  303.         item can be directly taken from PM_FindItem() as the input is
  304.         checked against NULL pointers.
  305.  
  306.    EXAMPLE
  307.  
  308.         struct PopupMenu *menu;
  309.         struct Image *image;
  310.         BOOL checked;
  311.  
  312.         ....
  313.         /* Initialize the menu */
  314.         ....
  315.  
  316.         PM_GetItemAttrsA(PM_FindItem(menu, itemid),
  317.                 PM_SelectImage, &image,
  318.                 PM_Checked,     &checked,
  319.                 TAG_DONE);
  320.  
  321.    INPUTS
  322.         item = pointer to a popup menu item.
  323.         tags = array of TagItem structures with attribute/value pairs.
  324.  
  325.    RESULT
  326.         Returns the number of successfully copied attributes.
  327.         
  328.    SEE ALSO
  329.         PM_FindItem()
  330.  
  331. popupmenu.library/PM_GetVersion               popupmenu.library/PM_GetVersion
  332.  
  333.    NAME
  334.         PM_GetVersion -- Get the library version string (V9)
  335.  
  336.    SYNOPSIS
  337.         version = PM_GetVersion();
  338.         D0                  
  339.  
  340.         STRPTR PM_GetVersion(void);
  341.  
  342.    FUNCTION
  343.         This function is used by the preferences program to find out which
  344.         settings that are supported by the library.
  345.  
  346.    RESULT
  347.         A version string containing version number & date.
  348.  
  349.    EXAMPLE
  350.  
  351.         puts(PM_GetVersion());
  352.  
  353.         Outputs the string:
  354.         "$VER: popupmenu.library 9.0 (01.05.00)"
  355.  
  356. popupmenu.library/PM_InsertMenuItemA     popupmenu.library/PM_InsertMenuItemA
  357.  
  358.    NAME
  359.         PM_InsertMenuItemA -- Insert menu items in a menu after creation.
  360.  
  361.    SYNOPSIS
  362.         success = PM_InsertMenuItemA(menu, tags);
  363.                                      a0    a1
  364.  
  365.         success = PM_InsertMenuItem(menu, tag1, ...);
  366.  
  367.         LONG PM_InsertMenuItemA(struct PopupMenu *, struct TagItem *);
  368.  
  369.         LONG PM_InsertMenuItem(struct PopupMenu *, ULONG tag1, ...);
  370.  
  371.    FUNCTION
  372.         This function inserts one or more items in a menu, after it has
  373.         been created with PM_MakeMenuA().
  374.  
  375.    INPUTS
  376.         menu - pointer to the menu that will recieve the new items.
  377.         tags - see below.
  378.  
  379.    RETURNS
  380.         The function returns the number of succesfully inserted items.
  381.         (0 if none was inserted)
  382.  
  383.    TAGS
  384.         PM_Insert_Item     (struct PopupMenu *)
  385.                            This tag inserts the item pointed to by ti_Data
  386.                            at the position formerly given by one of the
  387.                            tags below. (see example)
  388.  
  389.         PM_InsertAfter     (struct PopupMenu *)
  390.                            Insert the item(s) after this item.
  391.  
  392.         PM_InsertAfterID   (ULONG)
  393.                            Insert the item(s) after an item with this ID.
  394.  
  395.         PM_InsertSub_First (struct PopupMenu *)
  396.         PM_InsertSub_Last  (struct PopupMenu *)
  397.                            Insert the item(s) at the top/bottom of the
  398.                            submenu pointed to by ti_Data.
  399.  
  400.    EXAMPLE
  401.  
  402.         PM_InsertMenuItem(mypopupmenu,
  403.                 PM_InsertAfterID,   100,
  404.                 PM_Insert_Item,     PM_MakeItem(
  405.                                           PM_Title,  "New item",
  406.                                           TAG_DONE),
  407.  
  408.                 PM_InsertSub_First, a_submenu,
  409.                 PM_Insert_Item,     another_new_item,
  410.                 TAG_DONE);
  411.  
  412.    SEE ALSO
  413.         PM_RemoveMenuItem(), PM_MakeMenuA(), <libraries/pm.h>
  414.  
  415. popupmenu.library/PM_ItemChecked             popupmenu.library/PM_ItemChecked
  416.  
  417.    NAME
  418.         PM_ItemChecked -- Find out if an item is checked. (V3)
  419.  
  420.    SYNOPSIS
  421.         item = PM_ItemChecked(menu, id);
  422.         D0                    A1    D1
  423.  
  424.         BOOL PM_ItemChecked(struct PopupMenu *, ULONG);
  425.  
  426.    FUNCTION
  427.         Fast way to find out if an item is checked using the item ID.
  428.  
  429.    INPUTS
  430.         menu = pointer to a popup menu list.
  431.         id   = ID number (PM_ID).
  432.  
  433.    RESULT
  434.         TRUE (-1L) if the item is checked, FALSE (0L) if not checked,
  435.         PMERR (-5L) if the ID was not found in the list.
  436.         
  437. popupmenu.library/PM_LayoutMenuA             popupmenu.library/PM_LayoutMenuA
  438.  
  439.    NAME
  440.         PM_LayoutMenuA -- Prepare the menu for opening. (V9)
  441.  
  442.    SYNOPSIS
  443.         success = PM_LayoutMenuA(window, menu, tags);
  444.         D0                       A0      A1    A2
  445.  
  446.         success = PM_LayoutMenu(window, menu, tag1, ...);
  447.  
  448.         BOOL PM_LayoutMenuA(struct Window *, struct PopupMenu *,
  449.                         struct TagItem *);
  450.  
  451.         BOOL PM_LayoutMenu(struct Window *, struct PopupMenu *, ULONG, ...);
  452.  
  453.    FUNCTION
  454.         Loads and remaps images and lays out the menu. Use with large menus
  455.         that will only be used on one screen. This will speed up the menu
  456.         significantly.
  457.  
  458.    INPUTS
  459.         window = window on the screen you want to open the menu on later. The
  460.                  window must remain open until the menu is freed.
  461.                  You must not attempt to open the menu on another screen than
  462.                  the one the window is on. It may work sometimes, but don't
  463.                  count on it.
  464.         menu   = pointer to a popup menu list (PM_MakeMenuA).
  465.  
  466.    TAGS
  467.         No tags have been defined yet.
  468.  
  469.    RESULT
  470.         TRUE (-1L) if succesful, FALSE (0L) otherwise. Even if the function
  471.         would fail, you can still safely call PM_OpenPopupMenu().
  472.         
  473. popupmenu.library/PM_MakeIDListA             popupmenu.library/PM_MakeIDListA
  474.  
  475.    NAME
  476.         PM_MakeIDListA -- Create a list of ID's for exclusion/inclusion.
  477.  
  478.    SYNOPSIS
  479.         list = PM_MakeIDListA(taglist);
  480.         d0                 a1
  481.  
  482.         struct PM_IDLst *PM_MakeIDListA(struct TagItem *tags);
  483.  
  484.         list = PM_MakeIDList(tag1, ...);
  485.  
  486.         struct PM_IDLst *PM_MakeIDList(ULONG, ...);
  487.  
  488.    FUNCTION
  489.         This function is used to create a list of ID's that is used to
  490.         tell wich items an item should include, exclude, reflect or
  491.         inverse reflect.
  492.  
  493.    INPUTS
  494.         taglist - pointer to a taglist.
  495.  
  496.    TAGS
  497.         PM_ExcludeID   (ULONG) ID of a item that should be unselected when
  498.                        when this item is selected.
  499.  
  500.         PM_IncludeID   (ULONG) ID of a item that should be selected when
  501.                        when this item is selected.
  502.  
  503.         PM_ReflectID   (ULONG) ID of a item that should copy the state
  504.                        of this item, when it gets selected/unselected.
  505.  
  506.         PM_InverseID   (ULONG) ID of a item that should copy the inverse
  507.                        state of this item, when it gets selected/
  508.                        unselected.
  509.                        Useful if you want to make sure only one of two
  510.                        items is selected at a time.
  511.  
  512.    RETURNS
  513.         Returns a pointer to a list of id's if successful.
  514.  
  515.    SEE ALSO
  516.         PM_MakeItemA(), PM_ExLstA(), <libraries/pm.h>
  517.  
  518. popupmenu.library/PM_MakeItemA                 popupmenu.library/PM_MakeItemA
  519.  
  520.    NAME
  521.         PM_MakeItem -- Create a new menu item.
  522.  
  523.    SYNOPSIS
  524.         menu = PM_MakeItemA(taglist);
  525.         d0               a1
  526.  
  527.         struct PopupMenu *PM_MakeItemA(struct TagItem *tags);
  528.  
  529.         menu = PM_MakeItem(tag1, ...);
  530.  
  531.         struct PopupMenu *PM_MakeItem(ULONG, ...);
  532.  
  533.    FUNCTION
  534.         This function is used to create a new menu item to be passed to
  535.         PM_MakeMenuA(), for linking.
  536.  
  537.    INPUTS
  538.         taglist - pointer to a taglist listing your menu items.
  539.  
  540.    TAGS
  541.         PM_Title       (STRPTR) Pointer to the menu text you want.
  542.  
  543.         PM_UserData    (ULONG) Anything of your choice, can be used to
  544.                        identify the item when it is selected. The value
  545.                        stored here will be returned from PM_OpenPopupMenuA()
  546.                        when the user selects this item.
  547.  
  548.         PM_ID          (ULONG) An ID number, only needed if you want to
  549.                        be able to read or change the attributes of this
  550.                        item later. (for example, to find out if an item
  551.                        is checked)
  552.  
  553.         PM_Sub         (struct PopupMenu *) A pointer to a menu list
  554.                        returned from PM_MakeMenuA(). The item
  555.                        will automatically get an arrow to the right
  556.                        showing that it has a sub menu.
  557.  
  558.         PM_Flags       (ULONG) Used internally. Do not use this tag!
  559.  
  560.         PM_NoSelect    (BOOL) Make the item unselectable.
  561.                        If this attribute is set to FALSE for items with
  562.                        submenus, they will become selectable. Note that
  563.                        this is not currently (V8) reversable.
  564.  
  565.         PM_FillPen     (BOOL) Draw the item title in FILLPEN.
  566.  
  567.         PM_Checkit     (BOOL) Leave some space for a checkmark.
  568.  
  569.         PM_Checked     (BOOL) Put a checkmark to the left of the item.
  570.  
  571.         PM_Italic      (BOOL) Draw the text in italic.
  572.  
  573.         PM_Bold        (BOOL) Make the text bold.
  574.  
  575.         PM_Underlined  (BOOL) Underline the text.
  576.  
  577.         PM_WideTitleBar (BOOL)
  578.         PM_TitleBar    (BOOL) Draw a horizontal separator instead of text.
  579.  
  580.         PM_ShadowPen   (BOOL) Draw the text in SHADOWPEN color.
  581.  
  582.         PM_ShinePen    (BOOL) Draw the text in SHINEPEN color.
  583.  
  584.         PM_Exclude     (struct PM_IDLst *) List of items to be selected
  585.                        or unselected when this item gets selected.
  586.                        The list should be created with PM_MakeIDListA().
  587.  
  588.         PM_Disabled    (BOOL) Makes the item unselectable, and draws a
  589.                        disable pattern over the item.
  590.  
  591.         PM_ImageSelected (struct Image *)
  592.         PM_ImageUnselected (struct Image *)
  593.                        Specifies an image to be rendered under the item
  594.                        title.
  595.  
  596.         PM_IconSelected (struct Image *)
  597.         PM_IconUnselected (struct Image *)
  598.                        Specifies an image to be rendered to the left of the
  599.                        item title.
  600.  
  601.         PM_AutoStore   (BOOL *) A pointer to a BOOL that will reflect the
  602.                        state of the checkmark. The best way to find out
  603.                        if an item is checked or not.
  604.  
  605.         PM_TextPen     (ULONG) A pen number for the text. You are
  606.                        responsible for allocating/deallocating a pen
  607.                        yourself.
  608.  
  609.         PM_Shadowed    (BOOL) Give the the text a shadow using SHADOWPEN.
  610.  
  611.         PM_CommKey     (STRPTR) Keyboard shortcut for this item.
  612.                        Only the first character will be used. This is a
  613.                        string pointer just to make it easier to use locale
  614.                        strings for the shortcuts.
  615.  
  616.         PM_ColourBox   (ULONG) Draws a filled rectangle in using the
  617.                        specified pen.
  618.                        The box will be drawn at the end of the line in
  619.                        PM_CheckIt items, and at the beginning in other items.
  620.  
  621.         PM_SubConstruct (struct Hook *)
  622.                        This hook will be called before the submenu pointed to
  623.                        by PM_Sub is opened. Using this hook you can create the
  624.                        menu just before it is opened, and show directory
  625.                        contents etc in the menu. Remember to always free the
  626.                        pm->Sub pointer before replacing it with the new one.
  627.                        The hook function will recieve a pointer to the hook
  628.                        structure in A0 and a pointer to the selected (parent)
  629.                        menuitem in A2.
  630.  
  631.         PM_SubDestruct (struct Hook *)
  632.                        This hook is called after the submenu has been closed,
  633.                        and is typically used when you need to free user data.
  634.                        The hook function will recieve a pointer to the hook
  635.                        structure in A0 and a pointer to the parent menuitem
  636.                        in A2. (NOT the submenu!)
  637.  
  638.         PM_Hidden      (BOOL)
  639.                        Setting this tag to TRUE will prevent the item from
  640.                        being drawn.
  641.  
  642.         PM_TitleID     (ULONG)
  643.                        Locale string ID. Will be passed to the GetString
  644.                        hook. (see PM_OpenPopupMenuA()).
  645.  
  646.         PM_Object      (Object *)
  647.                        A BOOPSI object should be used to render this item.
  648.  
  649.         PM_Members     (PopupMenu *)
  650.                        Turns this item into a group, and adds the objects
  651.                        pointed to by ti_Data. The list of objects are
  652.                        created just like a (sub)menu with PM_MakeMenuA().
  653.                        The default layout mode is PML_Horizontal.
  654.  
  655.         PM_LayoutMode  (ULONG)
  656.                        Layout method (applies only to group items).
  657.                        Available layout methods are:
  658.  
  659.                        PML_Horizontal - Items are laid out horizontally.
  660.                        PML_Vertical   - Items are laid out vertically.
  661.  
  662.  
  663.  
  664.    RETURNS
  665.         Returns a pointer to an item if successful.
  666.  
  667.    SEE ALSO
  668.         PM_MakeMenuA(), PM_MakeIDListA(), PM_ExLstA(), PM_OpenPopupMenuA()
  669.  
  670. popupmenu.library/PM_MakeMenuA                 popupmenu.library/PM_MakeMenuA
  671.  
  672.    NAME
  673.         PM_MakeMenu -- Create a new menu list.
  674.  
  675.    SYNOPSIS
  676.         menu = PM_MakeMenuA(taglist);
  677.         d0               a1
  678.  
  679.         struct PopupMenu *PM_MakeMenuA(struct TagItem *tags);
  680.  
  681.         menu = PM_MakeMenu(tag1, ...);
  682.  
  683.         struct PopupMenu *PM_MakeMenu(ULONG, ...);
  684.  
  685.    FUNCTION
  686.         This function is used to link menu items returned by
  687.         PM_MakeItemA().
  688.  
  689.    INPUTS
  690.         taglist - pointer to a taglist listing your menu items.
  691.  
  692.    TAGS
  693.         PM_Item - pointer to a menuitem returned from PM_MakeItemA().
  694.  
  695.    RETURNS
  696.         Returns a pointer to a list of items if successful.
  697.  
  698.    SEE ALSO
  699.         PM_MakeItemA()
  700.  
  701. popupmenu.library/PM_OpenPopupMenuA       popupmenu.library/PM_OpenPopupMenuA
  702.  
  703.    NAME
  704.         PM_OpenPopupMenuA -- Open a popup menu.
  705.  
  706.    SYNOPSIS
  707.         userdata = PM_OpenPopupMenuA(prevwnd, taglist);
  708.         d0                        a1       a2
  709.  
  710.         ULONG PM_OpenPopupMenuA(struct Window *prevwnd, struct TagItem *tags);
  711.  
  712.         userdata = PM_OpenPopupMenu(prevwnd, tag1, ...);
  713.  
  714.         ULONG PM_OpenPopupMenu(struct Window *, ULONG, ...);
  715.  
  716.    FUNCTION
  717.         This function is used to open a popup menu based on an item list
  718.         created with PM_MakeMenuA()
  719.  
  720.    INPUTS
  721.         prevwnd - pointer to parent window, used to find out screen, font
  722.                   and other drawing attributes.
  723.         taglist - pointer to a taglist of menu options.
  724.  
  725.    TAGS
  726.         PM_Menu             (struct PopupMenu *) Pointer to a menu list
  727.                             created by PM_MakeMenuA().
  728.  
  729.         PM_RecessSelected   OBSOLETE!
  730.         PM_WideSelectBar    OBSOLETE!
  731.         PM_Compact          OBSOLETE!
  732.         PM_SubMenuTimer     OBSOLETE!
  733.         PM_OldLook          OBSOLETE!
  734.         PM_SameHeight       OBSOLETE!
  735.         PM_CheckMark        OBSOLETE!
  736.         PM_ExcludeMark      OBSOLETE!
  737.         PM_SubMenuMark      OBSOLETE!
  738.         PM_SmartRefresh     OBSOLETE!
  739.         
  740.         PM_Left             (ULONG) Horizontal position of the menu, relative
  741.                             to the menus left edge. (V3)
  742.  
  743.         PM_Top              (ULONG) Vertical position of the menu, relative
  744.                             to the menus top edge. (V3)
  745.  
  746.         PM_Code             OBSOLETE!
  747.  
  748.         PM_PullDown         (BOOL) Turn the menu into a pulldown menu. (V5.1)
  749.  
  750.         PM_MenuHandler      (struct Hook *) Menu handler function (hook). (V6.0)
  751.  
  752.         PM_Right            (ULONG) Horizontal position of the menu, relative
  753.                             to the menus right edge. (V7.3)
  754.  
  755.         PM_Bottom           (ULONG) Vertical position of the menu, relative
  756.                             to the menus bottom edge. (V7.3)
  757.  
  758.         PM_CenterScreen     (BOOL) Center the menu on the screen. (V7.3)
  759.  
  760.         PM_UseLMB           (BOOL) Reverses the function of the mouse buttons.
  761.                             Left button will be used to select items, and right
  762.                             button to select multiple items. This tag is only
  763.                             required when multiselect is used, and the menus is
  764.                             opened with LMB. (V7.3)
  765.  
  766.         PM_LocaleHook       (struct Hook *)     
  767.                             'GetString' hook used to get localized strings.
  768.                             The hook function will recieve a pointer to the
  769.                             menu item (struct PopupMenu *) in A2. A pointer
  770.                             to the Hook structure will be in A0, and an APTR
  771.                             pointer ("pointer to pointer") will be in A1.
  772.                             At the first location in this array is the string
  773.                             ID stored.
  774.                             A0. (V9)
  775.  
  776.         PM_ForceFont        (struct TextFont *)
  777.                             Render the menus using this font only. (V9)
  778.  
  779.         PM_HintBox          (BOOL)
  780.                             Make the menu dissappear when the mouse is moved.
  781.                             Intended for displaying "ToolTips". (Like the
  782.                             Help Bubbles in MUI, only they don't look like
  783.                             bubbles, and you have to handle the opening
  784.                             yourself. (V9)
  785.             
  786.  
  787.    RETURNS
  788.         Returns the value of UserData of the selected item, if no item
  789.         was selected, NULL is returned.
  790.  
  791.    SEE ALSO
  792.         PM_MakeMenuA()
  793.  
  794. popupmenu.library/PM_ReloadPrefs             popupmenu.library/PM_ReloadPrefs
  795.  
  796.    NAME
  797.         PM_ReloadPrefs -- Reload preferences. (V9)
  798.  
  799.    SYNOPSIS
  800.         PM_ReloadPrefs();
  801.  
  802.         void PM_ReloadPrefs(void);
  803.  
  804.    FUNCTION
  805.         This function is used by the preferences program to tell the library
  806.         to reload the settings file. ("ENV:popupmenu.cfg")
  807.  
  808. popupmenu.library/PM_RemoveMenuItem       popupmenu.library/PM_RemoveMenuItem
  809.  
  810.    NAME
  811.         PM_RemoveMenuItem -- Remove a menu item.
  812.  
  813.    SYNOPSIS
  814.         item = PM_RemoveMenuItem(menu, item);
  815.         d0                       a0    a1
  816.  
  817.         struct PopupMenu *PM_RemoveMenuItem(struct PopupMenu *,
  818.                                             struct PopupMenu *);
  819.  
  820.    FUNCTION
  821.         This function removes an item from a popup menu.
  822.         The removed item is NOT freed, you MUST free this item with
  823.         PM_FreePopupMenu(), unless you plan to reuse in another menu.
  824.         You may, for example, insert this item in another menu or at
  825.         another position in this menu, using the function
  826.         PM_InsertMenuItemA(). (but then ofcourse, you MUST NOT free the
  827.         item)
  828.  
  829.    INPUTS
  830.         menu - pointer to the holds the item to be removed.
  831.         item - pointer to the item to be removed.
  832.  
  833.    RETURNS
  834.         Returns a pointer to the removed item, or NULL if the item was not
  835.         present in the specified menu.
  836.         You are responsible for freeing this item!
  837.  
  838.    SEE ALSO
  839.         PM_MakeMenuA(), PM_FreePopupMenu(), PM_InsertMenuItemA()
  840.  
  841. popupmenu.library/PM_SetItemAttrsA         popupmenu.library/PM_SetItemAttrsA
  842.  
  843.    NAME
  844.         PM_SetItemAttrsA -- Specify attribute values for an object. (V3)
  845.  
  846.    SYNOPSIS
  847.         result = PM_SetItemAttrsA(item, tags);
  848.         D0                     A2    A1
  849.  
  850.         ULONG PM_SetItemAttrsA(struct PopupMenu *, struct TagItem *);
  851.  
  852.         result = PM_SetItemAttrs(item, tag1, ...);
  853.  
  854.         ULONG PM_SetItemAttrs(struct PopupMenu *, ULONG, ...);
  855.  
  856.    FUNCTION
  857.         Specifies a set of attribute/value pairs with meaning as
  858.         defined in libraries/pm.h.
  859.         item can be directly taken from PM_FindItem as the input is
  860.         checked against NULL pointers.
  861.  
  862.    EXAMPLE
  863.  
  864.         struct PopupMenu *menu;
  865.  
  866.         ....
  867.         /* Initialize the menu... */
  868.         ....
  869.  
  870.         PM_SetItemAttrsA( PM_FindItem( menu, itemid ),
  871.                 PM_Checkit,     TRUE,
  872.                 PM_Checked,     TRUE,
  873.                 TAG_DONE);
  874.  
  875.    INPUTS
  876.         item = pointer to a popup menu item.
  877.         tags = array of TagItem structures with attribute/value pairs.
  878.  
  879.    RESULT
  880.         Returns the number of successfully changed attributes.
  881.         
  882.